gitea runner 从 1.0.0 版本开始修改仓库名称和软件名称,现脚本同步全部修改
适用环境:Linux(AMD64 / ARM64)、systemd 管理的原生二进制部署。
默认目标版本:5.4.1
可执行文件:/usr/local/bin/gitea-runner
服务名称:gitea-runner
升级说明
本文用于升级通过 systemd 运行的 Gitea Actions Runner,不是 Docker 容器中的 Runner。升级脚本会自动识别 CPU 架构,下载官方二进制压缩包及 SHA256 文件,完成校验后才停止服务并替换程序。安装或启动检查失败时尝试恢复旧版可执行文件,成功后保留 .old 备份。
升级之前应确认 Runner 没有正在执行的 CI 作业,避免中断任务。本方案仅替换程序文件,不主动修改工作目录下的 .runner 注册信息或 config.yaml 配置。
运行环境及依赖
- 支持
x86_64 / amd64、aarch64 / arm64。 - 使用 root 运行;需要
bash、wget、xz、sha256sum、systemctl、install。 - 默认
gitea-runner.service的ExecStart指向/usr/local/bin/gitea-runner。 - 目标版本使用 Gitea 官方下载源
https://dl.gitea.com/gitea-runner/。
升级脚本
保存为 upgrade-gitea-runner.sh:
#!/usr/bin/env bash
set -Eeuo pipefail
# ================= 配置 =================
VERSION="${1:-5.4.1}"
SERVICE_NAME="gitea-runner"
INSTALL_PATH="/usr/local/bin/gitea-runner"
BACKUP_PATH="${INSTALL_PATH}.old"
DOWNLOAD_BASE="https://dl.gitea.com/gitea-runner"
# ================= 基础检查 =================
if [[ $EUID -ne 0 ]]; then
echo "错误:请使用 root 运行"
exit 1
fi
for cmd in wget xz sha256sum systemctl install mktemp sort; do
if ! command -v "$cmd" >/dev/null 2>&1; then
echo "错误:缺少命令 $cmd"
exit 1
fi
done
case "$(uname -m)" in
x86_64|amd64) ARCH="amd64" ;;
aarch64|arm64) ARCH="arm64" ;;
*) echo "错误:不支持的架构 $(uname -m)"; exit 1 ;;
esac
if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "错误:版本号必须是 x.y.z 格式"
exit 1
fi
# 1.0.0 之前的可执行文件名为 act_runner;
# 1.0.0 及之后使用 gitea-runner。
if [[ "$(printf '%s\n' "$VERSION" '1.0.0' | sort -V | head -n 1)" == "$VERSION" && "$VERSION" != '1.0.0' ]]; then
BINARY_NAME="act_runner-${VERSION}-linux-${ARCH}"
else
BINARY_NAME="gitea-runner-${VERSION}-linux-${ARCH}"
fi
DOWNLOAD_URL="${DOWNLOAD_BASE}/${VERSION}/${BINARY_NAME}.xz"
CHECKSUM_URL="${DOWNLOAD_URL}.sha256"
printf '版本:%s\n架构:%s\n下载:%s\n' "$VERSION" "$ARCH" "$DOWNLOAD_URL"
TMP_DIR="$(mktemp -d)"
SERVICE_STOPPED=false
BACKUP_CREATED=false
INSTALLED_NEW=false
cleanup() {
rm -rf -- "$TMP_DIR"
}
rollback() {
local code=$?
trap - ERR
if [[ "$SERVICE_STOPPED" == true ]]; then
echo "升级失败,开始恢复旧版本……"
if [[ "$BACKUP_CREATED" == true && -f "$BACKUP_PATH" ]]; then
systemctl stop "$SERVICE_NAME" || true
cp -a -- "$BACKUP_PATH" "$INSTALL_PATH"
if systemctl start "$SERVICE_NAME"; then
echo "旧版本已恢复并发起启动,请继续检查日志。"
else
echo "错误:旧版本恢复后服务仍未启动,请手动检查。" >&2
fi
else
echo "错误:没有可用的备份,请手动恢复。" >&2
fi
fi
exit "$code"
}
trap cleanup EXIT
trap rollback ERR
cd "$TMP_DIR"
echo '[1/6] 下载程序及 SHA256 校验文件'
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz" "$DOWNLOAD_URL"
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz.sha256" "$CHECKSUM_URL"
echo '[2/6] 检查 SHA256'
sha256sum -c "${BINARY_NAME}.xz.sha256"
echo '[3/6] 解压并确认可执行文件'
xz -d "${BINARY_NAME}.xz"
chmod 0755 "$BINARY_NAME"
"./${BINARY_NAME}" --version
echo '[4/6] 停止服务并备份旧版本'
# 必须先确认服务存在、安装目标文件存在。
systemctl cat "$SERVICE_NAME" >/dev/null
[[ -f "$INSTALL_PATH" ]] || { echo "错误:找不到旧程序 $INSTALL_PATH"; exit 1; }
systemctl stop "$SERVICE_NAME"
SERVICE_STOPPED=true
cp -a -- "$INSTALL_PATH" "$BACKUP_PATH"
BACKUP_CREATED=true
echo '[5/6] 安装新版本'
install -m 0755 "$BINARY_NAME" "$INSTALL_PATH"
INSTALLED_NEW=true
"$INSTALL_PATH" --version
echo '[6/6] 启动并检查服务'
systemctl start "$SERVICE_NAME"
sleep 3
systemctl is-active --quiet "$SERVICE_NAME"
SERVICE_STOPPED=false
echo '========================================'
echo 'Gitea Runner 升级成功'
"$INSTALL_PATH" --version
echo "服务状态:$(systemctl is-active "$SERVICE_NAME")"
echo "旧版备份:$BACKUP_PATH"
echo '========================================'
systemctl --no-pager status "$SERVICE_NAME"
注意:
.old是单份备份;下一次运行该脚本会覆盖它。自动回滚仅处理脚本执行期间检测到的失败,无法保证发现启动数分钟后才发生的问题。若原程序不在上述路径,需同步修改INSTALL_PATH并检查 systemd 服务。
执行升级
# 授予执行权限
chmod +x upgrade-gitea-runner.sh
# 默认升级到 5.4.1
sudo ./upgrade-gitea-runner.sh
# 或显式指定版本
sudo ./upgrade-gitea-runner.sh 5.4.1
升级前可检查服务和现有版本:
systemctl cat gitea-runner
/usr/local/bin/gitea-runner --version
systemctl status gitea-runner
升级后验证
# 检查程序版本
/usr/local/bin/gitea-runner --version
# 检查服务状态
systemctl is-active gitea-runner
systemctl status gitea-runner --no-pager
# 查看最近 50 条日志
journalctl -u gitea-runner -n 50 --no-pager
# 持续观察日志
journalctl -u gitea-runner -f
除服务处于 active 外,还应在 Gitea 管理界面确认 Runner 在线,并运行一个简单的 Actions 工作流,核对作业拉取、执行和日志回传均正常。
手动回滚
升级成功后如发现兼容性问题,可恢复旧版本:
sudo systemctl stop gitea-runner
sudo cp -a /usr/local/bin/gitea-runner.old /usr/local/bin/gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner --no-pager
/usr/local/bin/gitea-runner --version
确认不再需要旧版本时,才删除备份:
sudo rm -f /usr/local/bin/gitea-runner.old
常见问题
1. wget 下载失败或返回 404
检查版本号和架构是否有对应发行文件:
5.4.1 的 Linux AMD64 / ARM64 都提供 .xz 压缩包和 .xz.sha256 校验文件。
2. SHA256 校验失败
不要继续安装;优先删除临时下载文件后重新下载。检查代理、镜像缓存或传输链路是否使压缩包与校验文件不一致。脚本默认遇错停止。
3. 服务无法启动
systemctl cat gitea-runner
journalctl -xeu gitea-runner --no-pager
systemctl status gitea-runner --no-pager
重点核对 ExecStart、WorkingDirectory、服务用户权限及配置文件路径。
4. 版本升级与配置兼容性
不同大版本可能存在配置或工作流兼容性变化。升级到 6.x 之前请阅读官方升级说明。本文以 5.4.1 为默认版本,不会自动选择最新版本。
5. Docker 部署不适用
如果 Runner 是通过 Docker Compose 运行,应更新镜像版本并重新创建容器,而不是在宿主机上替换 /usr/local/bin/gitea-runner。